﻿<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="cs" lang="cs">
	<head>
		<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
		<meta name="revisit-after" content="1 days" />
		
		<meta name="classification" content="homepage" />

		<meta http-equiv="content-language" content="cs" />
		
		<meta http-equiv="description" content="Dwarf Fortress SoundSense" />
		<meta http-equiv="keywords" content="dwarf fortress sound engine music" />

		<meta name="reply-to" content="" />
		<meta name="author" content="Petr Prokop" />
		
		<meta name="robots" content="index,FOLLOW" />
		<meta name="resource-type" content="document" />
		
		<link href="../css/style.css" rel="stylesheet" type="text/css" />
		<link href="../css/scripture.css" rel="stylesheet" type="text/css" />
		<link rel="shortcut icon" href="../img/icon.png" type="image/png" />

		<link rel="home" title="Home" href="index.html" />
  
	  	<title>Dwarf Fortress: SoundSense</title>
	</head>

<body>

<div id="body">

	<div id="head">
	
		<h1>Dwarf Fortress SoundSense</h1>
		
		<p>an auditory treatment for humans</p>

	</div>
	
	<div id="content">
	
		<div id="minimenu"> <a href="../">Dwarf Fortress info</a> | <a href="../achievement">Achievement tool</a> | <a href="../soundsense">SoundSense</a> | <a href="../historian">Historian</a></div>
	
		<h2>What is SoundSense?</h2>
	
		<p class="first"><span class="scripture s"><span>S</span></span>oundSense is a sound-engine tool for <a href="../index.html">Dwarf Fortress</a>. It plays sounds based on what
		entries appear in the gamelog.txt. There is a thread at the <a href="http://www.bay12forums.com/smf/index.php?topic=60287">official dwarf fortress forums</a>, feel free to post your ideas and contributions there.
		You can also check out <a href="http://df.magmawiki.com/index.php/Utility:SoundSense">wiki page</a> for know issues and other documentation.</p>

		<div class="box">
			<object width="400" height="250"><param name="movie" value="http://www.youtube.com/v/RSX3piF5ww8?hl=cs&fs=1"></param><param name="allowFullScreen" value="true"></param><param name="allowscriptaccess" value="always"></param><embed src="http://www.youtube.com/v/RSX3piF5ww8?hl=cs&fs=1" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" width="400" height="250"></embed></object>
			<span>
				Tantrum spiral, in style! <a href="http://www.youtube.com/watch?v=P5LjuCxIRJA">part 2</a>, <a href="http://www.youtube.com/watch?v=EgyZsU5df_0">part 3</a> 
			</span>
		</div>
		
		<hr />
		
		<h2>Downloads:</h2>
		
		<p class="first"><span class="scripture r"><span>R</span></span>equires <a href="http://java.sun.com/javase/downloads/index.jsp">java 1.6</a> runtime.
		Install by unzipping to the Dwarf Fortress directory. For alternate location, you can edit <tt>soundSenseExe.cmd</tt> and change second to last parameter.
		Run by running <tt>soundSenseExe.cmd</tt>.</p>
		
		<div class="box">
			<span class="download">
				<a class="main_download" href="soundSense_@app.release@_@app.buildNum@.zip">SoundSense r@app.release@</a>
				<span class="main_download_info">@app.size@, @app.date@</span>
				<a class="main_download" href="soundpack.zip">Soundpack</a>
				<span class="main_download_info">@packs.size@, @packs.date@</span>
				<span class="main_download_info"><g:plusone></g:plusone></span> 
			</span>
		</div>
		
		<p>Remember to add official sound pack (separate download) or to run automated update after instalation!</p>
		
		<div class="box">
			<span>
				Older versions:
					<li><a href="soundSense_42_186.zip">release 42</a> (0.7 MB)</li>
					<li><a href="soundSense_41_181.zip">release 41</a> (0.7 MB)</li>
					<li><a href="soundSense_40_178.zip">release 40</a> (0.7 MB)</li>
					<li><a href="soundSense_39_177.zip">release 39</a> (0.7 MB)</li>
					<li><a href="soundSense_38_174.zip">release 38</a> (0.7 MB)</li>
					<li><a href="soundSense_37_167.zip">release 37</a> (0.7 MB)</li>
					<li><a href="soundSense_36_166.zip">release 36</a> (0.7 MB)</li>
					<li><a href="soundSense_35_165.zip">release 35</a> (0.7 MB)</li>
					<li><a href="soundSense_34_162.zip">release 34</a> (0.7 MB)</li>
					<li>...</li>
					<li><a href="soundSense_28_133.zip">release 28</a> (0.5 MB)</li>
					<li>...</li>
					<li><a href="soundSense_23_105.zip">release 23</a> (9.2 MB)</li>
				</ul>
			</span>
		</div>
		
		<hr />

		<h2>Instalation</h2>

		<p class="first"><span class="scripture i"><span>I</span></span>nstalation and setting it up can be intimidating task if you are not an IT nerd, but bear with us, it can actually be easy (and fun).</p>
		
		<div class="box">
			<span>
				Non-scary instructions:
				<ul>
					<li><a href="http://java.sun.com/javase/downloads/index.jsp">Install java runtime</a></li>
					<li>Download and extract soundsense, does not matter where.</li>
					<li>Download soundpack to packs directory in soundsense directory.</li>
					<li>Run soundsense.cmd or soundsense.exe</li>
				</ul>
			</span>
		</div>

		<p>First, you need to have java runtime installed. <a href="http://java.sun.com/javase/downloads/index.jsp">It can be downloaded from java homepage</a>. To see that you have correct instalation, go to Start->Run, type <tt>cmd</tt> in dialog that opens, press ok. You are now at commandline, type <tt>java -version</tt>. If everythig is okay, few lines starting with something similar to <tt>java version "1.6.0_14-ea"</tt> should apear, in that case you are cool to go.</p>

		<p>If something similar to <tt>'java' is not recognized as an internal or external command</tt> appears, you do not have properly set up instalation and can either <a href="http://www.cs.princeton.edu/introcs/15inout/windows-cmd.html">fix it</a> or work around it by editing <tt>soundSense.cmd</tt> which is in root of archive. Open it in Notepad and find line line starting with <tt>java -Dja...</tt> and replace <tt>java</tt> with full path for java instalation and java itself, for example <tt>"C:\Program Files\Java\jdk1.6.0_20\bin\java.exe"</tt>.</p>

		<p>So, hard issues are now handled :).</p>

		<p>Now, where to install it? SoundSense expects to be in directory that is inside your DF folder, so for example if you have DF in <tt>f:/df_31_12_win_s/</tt>, you should unpack contents of SoundSense zip to <tt>f:/df_31_12_win_s/soundSense</tt>. Basically, so that <tt>gamelog.txt</tt> is one directory above <tt>.cmd</tt> file you use to launch application.</p>

		<p>If you want to install in different location, you need to edit <tt>configuration.xml</tt> and edit <tt>path="../gamelog.txt"</tt>, replace <tt>../gamelog.txt</tt> with path to wherever it is located (for example with <tt>f:/df_31_12_win_s/gamelog.txt</tt>).</p>

		<p>It is now all set up and ready to run, but you need some sounds that it will actually play: Download <a href="soundpack.zip">soundpack.zip</a> and unzip it to directory <tt>packs</tt>.</p>
		
		<p>Now you can run SoundSense by launching <tt>soundSense.cmd</tt> or <tt>soundSenseExe.cmd</tt> (which should give you more sensible error messages regarding bad java instalation).</p>
		
		<div class="box">
			<object width="400" height="250"><param name="movie" value="http://www.youtube.com/v/4BNX_JWdXa0&amp;hl=cs_CZ&amp;fs=1?color1=0x3a3a3a&amp;color2=0x999999"></param><param name="allowFullScreen" value="true"></param><param name="allowscriptaccess" value="always"></param><embed src="http://www.youtube.com/v/4BNX_JWdXa0&amp;hl=cs_CZ&amp;fs=1?color1=0x3a3a3a&amp;color2=0x999999" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" width="400" height="250"></embed></object>
			<span>
				And there was much rejoicing!
			</span>
		</div>

		<hr />
		
		<h2>Sound Packs:</h2>
		
		<p class="first"><span class="scripture i"><span>I</span></span>nstall them by unzipping them to <tt>packs</tt> directory of the SoundSense.</p>
		
		<div class="box">
			<span>
				"Official soundpack"
				<ul>
					<li><a href="soundpack.zip">soundpack.zip</a> (@packs.size@, last update @packs.date@)</li>
				</ul>
				Credits for help for to <a href="http://www.krauselabs.net">tyrspawn</a> and Rainseeker :). Music from following sources was also used:
				<ul>
					<li><a href="http://www.reverbnation.com/simonswerwer">Simon Swerwer</a> - OST</li>
					<li><a href="http://roguebard.eptalys.net">Roguelike Bard</a></li>
					<li><a href="http://incompetech.com/m/c/royalty-free/index.html">Kevin MacLeod</a></li>
				</ul>
			</span>
		</div>
		
		<p>Official soundpack is work in progress, you can check out our status on <a href="https://code.google.com/p/df-soundsense/issues/list">tracking page</a>.</p>

		<div class="box">
			<span>
				<ul>
					<li>¤<a href="toikkus.zip">toikkus.zip</a>¤ (1.3 MB, last update 9.7.2010), Pack of announcements voiced by Toikkus from <a href="http://www.bay12forums.com">forums</a></li>
					<li>¤<a href="toikkus2.zip">toikkus2.zip</a>¤ (2.3 MB, last update 29.1.2011), Seccond pack of announcements voiced by Toikkus</li>
				</ul>
			</span>
		</div>
		
		<div class="box">
			<span>
				<ul>
					<li><a href="http://dffd.wimbli.com/file.php?id=2600">sphr's battle sounds</a></li>
					<li><a href="http://dl.dropbox.com/u/9398697/adventurer.zip">Zurack's adventurer mode sounds</a></li>
				</ul>
			</span>
		</div>
		
		<div class="box">
			<object width="400" height="250"><param name="movie" value="http://www.youtube.com/v/IiwOTQ2Kg8Y&amp;hl=cs_CZ&amp;fs=1?rel=0"></param><param name="allowFullScreen" value="true"></param><param name="allowscriptaccess" value="always"></param><embed src="http://www.youtube.com/v/IiwOTQ2Kg8Y&amp;hl=cs_CZ&amp;fs=1?rel=0" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" width="400" height="250"></embed></object>
			<span>
				Ah, welcome to our new home!
			</span>
		</div>

		<hr />
		
		<h2>Customization</h2>
		
		<div class="box">
			<span>
				Helpfull stuff:
				<ul>
					<li><a href="packSkeletons.zip">packSkeletons.zip</a> are xml files for all known
					log lines without sounds, you can use this as your starting point.</li>
					<li><tt>missingMessages.cmd</tt> will parse log file and output all lines
					your packs will not recognize</li>
					<li>Edit <tt>logging.properties</tt> to enable more debug messages from SS, set
					<tt>.level = ALL</tt> to view very verbose output.</li>
				</ul>
			</span>
		</div>
		
		<p class="first"><span class="scripture a"><span>A</span></span>dd sound by adding entry to xml configuration file. <tt>logPattern="regexp"</tt> is a
		<a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html">regular expression</a> which if matched, will cause random
		<tt>soundFile</tt> from sound element to be played.</p>
		
		<div class="box">
			<span>
				<tt>sound</tt> element attributes:
				<ul>
					<li><tt>logPattern</tt> - regular expression matching log line.</li>
					<li><tt>channel</tt> - string, channel on which sound is played. Sounds played on channel can be looped/stopped prematurely.</li>
					<li><tt>loop</tt> - string, "start" - sound start loop on channel until different sound is played on channel (if it is non-looped sound, loop will resume when it is done playing) or sound with "stop" is triggered.</li>
					
					<li><tt>concurency</tt> - number, number of councured sounds allowd to be played besides this sound. If currenty playing more than that, sound is ignored. In miliseconds, default unlimited.</li>
					<li><tt>timeout</tt> - number, timeout during which is sound going to be prevented from playing again. In miliseconds default 0.</li>
					<li><tt>propability</tt> - percentage, Propablity that sound will be played. Default is always played.</li>
					
					<li><tt>delay</tt> - number, delay before sound is played. In miliseconds, default 0.</li>
					<li><tt>haltOnMatch</tt> - boolean, if set to true, sound sense will stop processing long line after it was matched to this sound. Default false</li>
					
					<li><tt>ansiFormat</tt> - <a href="http://en.wikipedia.org/wiki/ANSI_escape_code">ANSI escape code</a>, used to color console output.</li>
				</ul>
			</span>
		</div>
		
		<div class="box">
			<span>
				<tt>soundFile</tt> element attributes:
				<ul>
					<li><tt>fileName</tt> - path to audio file with sound.</li>
					<li><tt>weight</tt> - number, controls likelihood of sound to be chosen. Defaulkt is 100.</li>
					<li><tt>volumeAdjustment</tt> - number, adjusts volume of sample. Can range from -40 to +6 decibles, default 0.</li>
					<li><tt>randomBalance</tt> - boolean, if set to true will randomply distribute sound betweem stereo channels.</li>
					<li><tt>balanceAdjustment</tt> - number, adjusts stereo channel, can range for -1 (full left) to 1 (full right).</li>
				</ul>
			</span>
		</div>
		
		<div class="box">
			<span>
				<tt>sounds</tt> element attributes:
				<ul>
					<li><tt>defaultAnsiColor</tt> - <a href="http://en.wikipedia.org/wiki/ANSI_escape_code">ANSI escape code</a>, used to color console output when nothing is defined at sounds.</li>
				</ul>
			</span>
		</div>
		
		<p>Sound can contain several <tt>soundFile</tt> elements, when it is triggered one random of them is triggered.
		You can control how often is particular sound chosen by <tt>weight="number"</tt> attribute.</p>
		
		<div class="box">
			<span>
				Supported formats for <tt>soundFiles</tt>:
				<ul>
					<li>mp3</li>
					<li>ogg</li>
					<li>wav</li>
					<li>aiff</li>
					<li>au</li>
				</ul>
			</span>
		</div>
		
		<p><tt>soundFile</tt> itself can be playlist instead of sound file itself, marked by <tt>playlist="true"</tt> attribute. Sound files in playlist inherit all
		properties of their soundfile parent.</p>
		
		<div class="box">
			<span>
				Supported formats for playlist:
				<ul>
					<li>pls</li>
					<li>m3u</li>
				</ul>
			</span>
		</div>
		
		<hr />
		
		<h2>Modding resources</h2>
		
		<div class="box">
			<span>
				Some sites of interest should you want additional sounds:
				<ul>
					<li><a href="http://soundbible.com/">http://soundbible.com/</a></li>
					<li><a href="http://www.freesound.org/">http://www.freesound.org/</a></li>
					<li><a href="http://www.musopen.org/">http://www.musopen.org/</a></li>
					<li><a href="http://opengameart.org/browse/audio">http://opengameart.org/browse/audio</a></li>
					<li><a href="http://www.incompetech.com/m/c/royalty-free/">http://www.incompetech.com/m/c/royalty-free/</a></li>
					<li><a href="http://ccmixter.org">http://ccmixter.org</a></li>
					<li><a href="http://free-loops.com/">http://free-loops.com/</a></li>
					<li><a href="http://www.pdsounds.org/">http://www.pdsounds.org/</a></li>
					<li><a href="http://commons.wikimedia.org/wiki/Category:Sound">http://commons.wikimedia.org/wiki/Category:Sound</a></li>
					<li><a href="http://www.archive.org/details/opensource_audio">http://www.archive.org/details/opensource_audio</a></li>
					<li><a href="http://publicdomainaudiovideo.blogspot.com/">http://publicdomainaudiovideo.blogspot.com/</a></li>
					
				</ul>
			</span>
		</div>
		
		<p>Excellent utility <a href="http://mp3gain.sourceforge.net/">mp3gain</a> can help with keeping volume of sounds matching.</p>
		
		<div class="box">
			<img src="ansi_codes.png" alt="Ansi Codes" />
			<span>Visual guide to ansi codes.</span>
		</div>
		
		<hr />
		
		<h2>Source Code</h2>
		
		<p class="first"><span class="scripture o"><span>O</span></span>pen source can be found at <a href="https://code.google.com/p/df-soundsense/">google code</a>, within soundsense distribution itself and here: <a class="main_download" href="soundSense_@app.release@_@app.buildNum@_source.zip">soundSense_@app.release@_@app.buildNum@_source.zip</a>.</p>

		<hr />
		
		<h2>Grand plan</h2>
		
		<p>Current development goals are to expand list of known events which we can react to and add apropriate sounds.</p>
		
		<hr />
		
	</div>
	
	<div id="footer">
	
		<span>A vile force of darkness has arrived!</span>
	
	</div>

	
</div>

<div id="true_footer">

	Petr '<a href="http://www.zweistein.cz">Zwei</a>' Prokop

</div>

</body>

<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
try {
var pageTracker = _gat._getTracker("UA-15785072-1");
pageTracker._trackPageview();
} catch(err) {}</script>

<script type="text/javascript">
  window.___gcfg = {
    lang: 'en-US'
  };

  (function() {
    var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
    po.src = 'https://apis.google.com/js/plusone.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
  })();
</script>

</html>